W05-2. Docker Compose - 실습 가이드

5주차 실습: 방명록 + PostgreSQL 을 Compose 로

실습 목표 (45분)

  • compose.yaml 과 .env 를 작성하고 명령 한 줄로 웹 + DB 를 띄운다.
  • 방명록 글이 PostgreSQL 에 저장되어, 컨테이너를 다시 만들어도 남아 있는 것을 확인한다.
  • logs, exec, down, down -v 의 차이를 직접 겪어 본다.
  • 웹을 3개로 늘려 보고 Compose 의 한계를 확인한다.

시작 전 확인

  • 4주차 실습의 docker-study/guestbook 폴더에 app.py, requirements.txt, Dockerfile, .dockerignore 가 있어야 합니다.
    • 없다면 4주차 실습 0 만 먼저 하세요(7분).
  • Docker Desktop 실행 중
  • 터미널에서 guestbook 폴더로 이동:
    • macOS: cd ~/docker-study/guestbook
    • Windows: cd "$HOME\docker-study\guestbook"
  • 오늘의 docker compose 명령은 macOS 와 Windows 가 똑같습니다.

실습 내용 시간
1 .env 와 compose.yaml 만들기 7분
2 한 줄로 띄우기 5분
3 방명록 쓰고 DB 에서 확인하기 7분
4 설정 · 코드 바꾸기 6분
5 down vs down -v 6분
6 웹을 3개로? (Compose 의 한계) 4분
7 코드 자동 반영: compose watch 7분
8 정리 3분

실습 1. .env 와 compose.yaml 만들기

VS Code 로 guestbook 폴더를 열고, 파일 두 개를 새로 만듭니다.

① .env (점으로 시작, 확장자 없음)

DB_PASSWORD=guestpw

② compose.yaml

services:
  web:
    build: .
    image: guestbook:compose
    ports:
      - "8080:8000"
    environment:
      APP_VERSION: v1-compose
      DATABASE_URL: postgresql://guest:${DB_PASSWORD}@db:5432/guestbook
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:18-alpine
    environment:
      POSTGRES_USER: guest
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: guestbook
    volumes:
      - db-data:/var/lib/postgresql
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U guest -d guestbook"]
      interval: 5s
      timeout: 3s
      retries: 10
    restart: unless-stopped

volumes:
  db-data:

③ .dockerignore 에 한 줄 추가: 맨 아래에 .env 를 추가하고 저장합니다.

__pycache__/
*.pyc
.venv/
.git/
.DS_Store
.env

비밀번호가 든 .env 가 이미지 안으로 들어가지 않게 막는 것입니다.

1-1. 문법 검사

docker compose config

출력 예시 (앞부분): ${DB_PASSWORD} 자리에 guestpw 가 채워져 보이면 .env 를 잘 읽은 것입니다.

name: guestbook
services:
  db:
    environment:
      POSTGRES_DB: guestbook
      POSTGRES_PASSWORD: guestpw
      POSTGRES_USER: guest
    healthcheck:
      test:
        - CMD-SHELL
        - pg_isready -h localhost -U guest -d guestbook
...
에러가 난다면

  • go-yaml load error in scanner at L5.C10: mapping values are not allowed in this context 같은 메시지 → 5번째 줄 근처의 들여쓰기가 틀렸습니다. 공백 칸 수를 위 예시와 똑같이 맞추세요.
  • ... found character that cannot start any token → 탭(Tab) 이 들어갔습니다. 공백으로 바꾸세요.
  • The "DB_PASSWORD" variable is not set 경고 → .env 파일 이름이나 위치가 틀렸습니다(compose.yaml 과 같은 폴더).
  • name: guestbook 부분은 폴더 이름입니다. 폴더 이름이 다르면 다르게 나옵니다.


실습 2. 한 줄로 띄우기

docker compose up -d

출력 예시: 처음에는 web 이미지를 빌드하고 시작합니다.

 Network guestbook_default  Created
 Volume guestbook_db-data  Created
 Container guestbook-db-1  Created
 Container guestbook-web-1  Created
 Container guestbook-db-1  Started
 Container guestbook-db-1  Waiting
 Container guestbook-db-1  Healthy
 Container guestbook-web-1  Started
순서를 보세요

db 시작 → Waiting(기다림) → Healthy → 그다음에 web 시작. depends_on 의 condition: service_healthy 가 동작한 것입니다.
3주차에 손으로 했던 네트워크 만들기, 볼륨 만들기, 순서 맞추기를 Compose 가 다 했습니다.

docker compose ps

출력 예시:

NAME              IMAGE                COMMAND                   SERVICE   CREATED          STATUS                    PORTS
guestbook-db-1    postgres:18-alpine   "docker-entrypoint.s…"   db        14 seconds ago   Up 14 seconds (healthy)   5432/tcp
guestbook-web-1   guestbook:compose    "gunicorn --bind 0.0…"   web       17 seconds ago   Up 9 seconds              0.0.0.0:8080->8000/tcp, [::]:8080->8000/tcp
확인할 점 의미
db 의 STATUS (healthy) healthcheck 가 통과 중
db 의 PORTS 5432/tcp 컨테이너 안에서만 열려 있음. 바깥에 공개 안 됨 (3주차의 안전한 방식)
web 의 PORTS 0.0.0.0:8080->8000/tcp 브라우저로 접속 가능

실습 3. 방명록 쓰고 DB 에서 확인하기

3-1. 브라우저

http://localhost:8080 을 열면 머리글 아래에 저장소: PostgreSQL 이 보입니다. 글을 2~3개 남겨 보세요.

http://localhost:8080/readyz 도 열어 봅니다.

{"status":"ready"}

/readyz 는 앱이 DB 까지 연결되는지 확인하는 주소입니다. 10주차에 다시 씁니다.

3-2. 로그 보기

docker compose logs --tail 3 web

출력 예시: 앞에 web-1 | 처럼 어느 서비스의 로그인지 표시됩니다.

web-1  | [2026-10-01 05:18:45 +0000] [1] [INFO] Using worker: gthread
web-1  | [2026-10-01 05:18:45 +0000] [7] [INFO] Booting worker with pid: 7
web-1  | [2026-10-01 05:18:45 +0000] [1] [INFO] Control socket listening at /home/appuser/.gunicorn/gunicorn.ctl

docker compose logs -f 로 전체 서비스의 로그를 실시간으로 볼 수도 있습니다. Ctrl + C 로 빠져나옵니다.

3-3. DB 안을 직접 들여다보기

docker compose exec db psql -U guest -d guestbook -c "SELECT id, name, body FROM messages;"

출력 예시:

 id |  name  |       body
----+--------+------------------
  1 | 김수종 | Compose 로 첫 글
  2 | 홍길동 | 안녕하세요
(2 rows)

브라우저에서 쓴 글이 PostgreSQL 테이블에 들어 있습니다.
docker compose exec 는 컨테이너 이름(guestbook-db-1) 대신 서비스 이름(db) 으로 부를 수 있어 편합니다.

3-4. web 이 db 를 이름으로 찾는지 확인

docker compose exec web python -c "import socket; print(socket.gethostbyname('db'))"

출력 예시: 172.24.0.2 (숫자는 다를 수 있음)

db 라는 서비스 이름이 IP 로 바뀌었습니다. 그래서 DATABASE_URL 에 @db:5432 라고 쓸 수 있었습니다.


실습 4. 설정 · 코드 바꾸기

4-1. 설정(환경 변수)만 바꾸기

VS Code 에서 compose.yaml 의 APP_VERSION: v1-compose 를 APP_VERSION: v1-compose-2 로 바꾸고 저장합니다.

docker compose up -d

출력 예시: 바뀐 web 만 다시 만들고, db 는 그대로 둡니다.

 Container guestbook-db-1  Running
 Container guestbook-web-1  Recreate
 Container guestbook-web-1  Recreated
 Container guestbook-db-1  Waiting
 Container guestbook-db-1  Healthy
 Container guestbook-web-1  Starting
 Container guestbook-web-1  Started

http://localhost:8080 → 머리글이 방명록 v1-compose-2 로 바뀌었고, 남긴 글은 그대로 있습니다.

up -d 는 "현재 상태를 파일 내용에 맞춰 줘" 라는 뜻

이미 떠 있으면 바뀐 것만 다시 만듭니다. 선언형 방식의 장점입니다.

4-2. 코드 바꾸기

app.py 에서 아직 글이 없습니다 가 들어간 줄의 문구를 아무렇게나 바꾸고 저장한 뒤:

docker compose up -d

→ 아무것도 다시 만들지 않습니다. Compose 는 이미 만든 이미지 guestbook:compose 를 그대로 씁니다.

docker compose up -d --build

→ 이번에는 이미지를 다시 빌드하고 web 을 다시 만듭니다.

기억할 것

바꾼 것 명령
compose.yaml (설정) docker compose up -d
소스 코드 / Dockerfile docker compose up -d --build


실습 5. down vs down -v

5-1. down: 컨테이너는 지우고 데이터는 남긴다

docker compose down

출력 예시:

 Container guestbook-web-1  Removed
 Container guestbook-db-1  Removed
 Network guestbook_default  Removed

Volume 은 지우지 않았습니다. 확인해 봅니다.

docker volume ls --filter name=guestbook

출력 예시:

DRIVER    VOLUME NAME
local     guestbook_db-data

다시 올립니다.

docker compose up -d

http://localhost:8080 → 컨테이너는 새것인데 글이 그대로 있습니다. 🎉

5-2. down -v: 볼륨까지 지운다

docker compose down -v

출력 예시:

 Container guestbook-web-1  Removed
 Container guestbook-db-1  Removed
 Volume guestbook_db-data  Removed
 Network guestbook_default  Removed
docker compose up -d

http://localhost:8080 → 남긴 글이 하나도 없습니다. 데이터가 영구히 사라졌습니다.

운영 환경에서 down -v 는 금지어입니다

DB 데이터가 통째로 사라집니다. 실습이 아니라면 쓰기 전에 반드시 백업하세요.


실습 6. 웹을 3개로? (Compose 의 한계)

방문자가 많아져서 웹을 3개로 늘리고 싶다고 해 봅시다.

docker compose up -d --scale web=3

출력 예시 (끝부분):

Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint guestbook-web-3 (...): Bind for 0.0.0.0:8080 failed: port is already allocated
왜 실패했을까요?

3개가 모두 노트북의 8080 포트를 쓰려고 했기 때문입니다. 포트 하나는 컨테이너 하나만 쓸 수 있습니다.
여러 개를 띄우고, 앞에서 하나의 주소로 받아 나눠 주는 장치(로드밸런서)가 필요합니다. → Kubernetes 의 Service (8주차)

원래대로 1개로 되돌립니다.

docker compose up -d --scale web=1
docker compose ps

guestbook-web-1 과 guestbook-db-1 만 남아 있으면 됩니다.


실습 7. 코드 자동 반영: compose watch

코드를 고칠 때마다 --build 를 치는 대신, 저장만 하면 자동으로 반영되게 할 수 있습니다(개발용 기능).

7-1. compose.yaml 에 develop 추가

web: 서비스의 restart: unless-stopped 아래에 다음을 추가합니다. 들여쓰기에 주의하세요(develop 은 restart 와 같은 칸).

    restart: unless-stopped
    develop:
      watch:
        - action: sync+restart
          path: ./app.py
          target: /app/app.py
        - action: rebuild
          path: ./requirements.txt
설정 의미
sync+restart app.py 를 저장하면 컨테이너 안의 /app/app.py 로 복사하고 web 을 재시작
rebuild requirements.txt 가 바뀌면 이미지를 다시 빌드

7-2. watch 시작

docker compose watch

출력 예시: Watch enabled 가 나오면 준비 완료입니다. 이 터미널은 그대로 둡니다.

 Container guestbook-db-1  Healthy
 Container guestbook-web-1  Started
Watch enabled

7-3. 코드를 고치고 저장만 하기

VS Code 에서 app.py 의 아직 글이 없습니다 가 들어간 줄의 문구를 바꾸고 저장합니다.

watch 터미널 출력 예시:

Syncing service "web" after 1 changes were detected
 Container guestbook-web-1  Restarting
 Container guestbook-web-1  Started
service(s) ["web"] restarted

브라우저를 새로고침하면 바뀐 문구가 보입니다. --build 없이 반영됐습니다.

7-4. watch 끝내기

watch 터미널에서 Ctrl + C 를 누릅니다.

watch 로 바꾼 내용은 실행 중인 컨테이너에만 있습니다

이미지에는 반영되지 않았습니다. 실제로 확인해 보니 docker compose down 후 up 을 하면 예전 문구로 돌아갔습니다.
고친 코드를 이미지에 넣으려면 마지막에 꼭 docker compose up -d --build 를 하세요.


실습 8. 정리

docker compose down
다음 주 준비

  • 볼륨은 지우지 않아도 됩니다. 6주차부터는 Kubernetes 를 쓰므로 이 Compose 환경은 더 쓰지 않습니다. 디스크를 비우고 싶다면 docker compose down -v 로 지워도 됩니다.
  • guestbook 폴더의 파일(compose.yaml, .env 포함)은 그대로 두세요.
  • Docker Hub 에 내아이디/guestbook:v1, v2 가 올라가 있는지 다시 확인하세요(4주차 실습 6). 6주차에 바로 씁니다.


자주 나는 문제와 해결

증상 원인 해결
no configuration file provided: not found compose.yaml 이 없는 폴더에서 실행 cd 로 guestbook 폴더로 이동
go-yaml load error ... at L5.C10: mapping values are not allowed in this context 들여쓰기 오류 (L5 = 5번째 줄) 예시와 칸 수를 똑같이. VS Code 오른쪽 아래가 Spaces: 2 인지 확인
go-yaml load error ... found character that cannot start any token 탭(Tab) 사용 탭을 공백으로 바꾸기
The "DB_PASSWORD" variable is not set. Defaulting to a blank string. .env 가 없거나 이름이 틀림 (.env.txt 등) compose.yaml 과 같은 폴더에 정확히 .env
dependency failed to start: container guestbook-db-1 is unhealthy DB 가 제시간에 준비되지 못함 docker compose logs db 로 원인 확인 후 docker compose up -d 다시
방명록에 Internal Server Error, 로그에 password authentication failed .env 의 비밀번호를 바꿨는데 예전 볼륨을 그대로 씀 비밀번호는 볼륨을 처음 만들 때만 적용됩니다. 실습이면 docker compose down -v 후 다시 up -d
Bind for 0.0.0.0:8080 failed: port is already allocated 4주차 컨테이너 등이 8080 을 쓰는 중 docker ps 로 찾아서 지우기 (docker rm -f 이름)
코드를 고쳤는데 반영이 안 됨 이미지를 다시 빌드하지 않음 docker compose up -d --build

오늘 쓴 명령어 정리

명령어 하는 일
docker compose config 문법 검사 + 최종 설정 보기
docker compose up -d 전부 실행 (바뀐 것만 다시 만듦)
docker compose up -d --build 이미지 다시 빌드 후 실행
docker compose up -d --scale web=3 서비스 개수 바꾸기
docker compose ps 상태 보기
docker compose logs [-f] [--tail N] [서비스] 로그 보기
docker compose exec 서비스 명령 서비스 안에서 명령 실행
docker compose watch 저장하면 자동 반영 (개발용)
docker compose down 컨테이너 · 네트워크 삭제 (볼륨 유지)
docker compose down -v 볼륨까지 삭제

복습 과제

확인 퀴즈

  1. compose.yaml 의 DATABASE_URL 에서 DB 주소를 @db:5432 라고 쓸 수 있는 이유는?
  2. depends_on 에 condition: service_healthy 를 붙이면 무엇이 달라지나요?
  3. docker compose down 과 docker compose down -v 의 차이는?
  4. app.py 를 고친 뒤 docker compose up -d 만 했더니 반영되지 않았습니다. 왜 그런가요?
  5. .env 파일을 Git 에 올리지 않고 .dockerignore 에도 넣는 이유는?
  6. --scale web=3 이 실패한 이유와, 이 문제를 해결하는 Kubernetes 기능은?

도전 과제 (선택)

  1. compose.yaml 에 Adminer(웹으로 DB 를 보는 도구)를 추가해 보세요. 아래를 services: 아래에 넣고 docker compose up -d → http://localhost:8081 에 접속합니다. 로그인 화면에서 시스템 PostgreSQL, 서버 db, 사용자 guest, 비밀번호 guestpw, 데이터베이스 guestbook.
      adminer:
        image: adminer:5
        ports:
          - "8081:8080"
        depends_on:
          - db
    
  2. docker compose ps 로 3개 서비스가 모두 떠 있는 것을 확인한 뒤 docker compose down 으로 정리합니다.
다음 주 예고: 6주차 Kubernetes 입문

Compose 로는 서버 한 대 안에서만 관리할 수 있었습니다. 다음 주부터는 여러 서버(노드)를 한 덩어리처럼 다루는 Kubernetes 를 시작합니다. Docker Desktop 에 Kubernetes 클러스터를 만들고, 내가 Docker Hub 에 올린 방명록을 Pod 로 띄웁니다.


네비게이션

이전 목록 다음
◀ 5주차 강의 노트 목록으로 6주차 강의 노트 ▶